'.\" t
.TH "lems.xml" "1M" "Sep 5, 2005" "1\&.2\&.3"
.SH NAME
lems.xml \- Linuxha.net Event Manager Config File

.SH SYNOPSIS
Definition of Linuxha.net Event Manager Config File

A sample configuration file may look similar to the following:

.TS
l.
<?xml version="1.0"?>
<lems_config>
    <globals modules="/sbin/cluster/lems/modules"
        programs="/sbin/cluster/lems/programs"
        logs="/var/log/cluster/lems"
    />
    <check>
        <name>flag_check</name>
        <type>internal</type>
        <module>flag_check samba</module>
        <interval>5</interval>
        <action_list>
            <action rc="0" action="NOP"/>
            <action rc="1" action="%RCDATA%"/>
            <action rc="2" action="ABORT"/>
        </action_list>
    </check>
</lems_config>
.TE

.SH INTRODUCTION
A single lems configuartion file typically exists for each application
that the Linuxha.net cluster hosts. The current software revisions expect
this file to have the following pathname:

.TS
l.
/etc/cluster/<appname>/lems.local.xml
.TE

The long-term intention is to introduce a "lems.remote.xml" which is 
run on nodes not currently running the application (i.e. when the 
application is running on a remote node).

As the filename suggests this file is an XML file and thus must
adhere to the standard guidelines for creating XML files. However 
as with other XML files handled by Linuxha.net - quotes can be used
as is - rather than having to use "&quot;".

.SH THE GLOBAL SECTION
In this section the information is defined as attributes to the "global"
element, and the following attributes must exist:

.TS
box expand;
l l.
Attribute	Purpose
_
modules	The directory where Lems modules reside - typically left as
	"/sbin/cluster/lems/modules".
programs	The directory where Lems programs can be found -
	typically left as "/sbin/cluster/lems/programs".
logs	The directory where the log files are created - typically
	"/var/log/cluster/lems".
.TE

.SH THE CHECK SECTIONS
Each check that is configured into the Lems configuration file will
have a separate "check" section. The Lems configuration file should
contain at least one of these sections; though many contain a good deal
more!

In this section the following attributes should all be present - none
are optional.

.TS
box expand;
l l.
Variable	Purpose
_
name	The name of the check. This should be a single work, and
	acts as a handle allowing this specific check to be
	managed if required.
type	The type of check should be either "internal" or
	"external".  When "internal" the module will be loaded as
	a perl module, whilst "external" entries are commands 
	that are executed every time the check is required.
module	The name of the module  or command to run, along with any
	arguments - that should be white-space separated. If the
	"type" is set to "module" then a file called "module.pm" 
	is expected to exist in the modules, directory, otherwise
	a command of this name is expected in the programs
	directory.
interval	The minimum interval between running the check. The
	maximum wait can not be defined since the current 
	implementation of this daemon is single threaded - so one
	module might hold up the execution of others if they take
	a long time to complete.
action_list	This can contain one or more "action" items
	which consist of attributes "rc" and "action". The "rc"
	is the return code of the command or module, whilst the
	"action" determines what to do in such circumstances.
.TE

.SS The Action List attributes
As stated above the "action" element contains two attributes, "rc"
and "action". The "rc" value consists of a single number, whilst the
"action" attribute can contain zero, one or more actions to undertake
if the specified return code it returned via running the specific modue.

A typical "action_list" section is likely to include several lines, 
such as:

.TS
l.
    <action rc="0" action="NOP"/>
    <action rc="1" action="%RCDATA%"/>
    <action rc="2" action="ABORT"/>
.TE

The actions available are limited, though mulitple actions are possible for the
same return code by separating each with a semicolon. The table below 
defines the available actions:


.TS
box expand;
l l.
Action	Purpose
_
NOP	No operation - do nothing. This is the default action assumed
	if the specified return code is not present in the
	"action_list" list for this monitor.
FAILOVER	Indicate that the local cluster daemon should 
	attempt to fail-over the currnet application to the other 
	node.  If the other node is not suitable then the 
	application will be stopped but no restarted.
RUNCMD	The remainder of the line is run as an external command. In this
	case the standard output and standard error of the command
	is directory to the files:
	/var/log/cluster/lems/\fBapplication\fP-\fBmon\fP.stdout
	/var/log/cluster/lems/\fBapplication\fP-\fBmon\fP.stderr
REMOVEMON	The current monitor is removed from the configuration
	completely. It will not be visible again unless reloaded
	by the administrator.
STOPAPP	Halt the current application without attempting to a fail-over
	to the other node.
RUN	Run a specified monitor. The name of the monitor should 
	follow and this is optionally followed by the frequency the
	monitor should be run at [defaulting to the currently defined
	frequency].
PAUSE	Indicates that the current monitor should be stopped. 
	Optionally a number of seconds can follow, which if not
	specified will default to 30. After the specified time
	period the monitoring will be resumed at the currently
	defined interval.
HALT	Stop monitoring for a specified monitor (which is a 
	mandatory first argument).
.TE

.SS Handling State Information
Where possible it is recommended that if a new module is required
then it should be coded as a Perl module rather than as an external
command.

The advantage of using a perl module is that it is easy to carry
around state information, and also to have several objects of
the same type running if necessary.

When using external commands the implementer is responsible for
ensuring that any necessary state information is loaded/stored
between each invocation of the check - which is both cumbersome
and expensive in terms of CPU time.

.SH SEE ALSO
.TS
l l.
lemsctl(1M)	- Lems daemon controlller program
lems.pl(1M)	- Lems daemon
clconf.xml(5)	- Cluster configuration file
appconf.xml(5)	- Configuration of an application used by the cluster
procmon.xml(5)	- Lems 'procmon' configuration file format
.TE

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
http://linuxha.net for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

